Copyright: © Paul Arnote. All Rights Reserved.
Citation: This file, and its textual content, are Copyright (c) 1995, Paul Arnote. All Rights Reserved. No portion of this file may be copied, via any means available, without the expressed and written consent of the author. The author is not responsible for any damages incurred, WHATSOEVER, from using this file or the information contained therein. No warranty, expressed or implied, is offered.


Table Of Contents
256 Color WinHelp Extension Library v2.0

Welcome to the 256 Color WinHelp Extension Library, which will allow you, among other things, to display 256 color and 24-bit bitmaps in Windows 3.1 Help files. You can also extract baggage files from Help’s internal file system to keep all the ancillary files of your project together until they are needed. See the end of this topic for a complete list of the sixteen (16) custom macros this DLL provides.

This library is presented as SHAREWARE. Feel free to distribute it with your projects, but registration disables the “nag” message at the beginning of every Help file that utilizes this DLL. Registration is only $20 and the registration code will be valid for all future updates/upgrades of this DLL. Plus, if you register now, you exempt yourself from any possible price increases for future versions/updates/upgrades. To register your copy, see the registration form in this Help file.

This Help file extension library is somewhat based upon the freeware DLL, EWDLL.DLL, by Ron Pacheco, professor of Mathematics and Computer Science at Harding University in Searcy, Arkansas, and upon the baggage file example by Jim Mischel, author of The Developer’s Guide to WinHelp.Exe. I have also made several additions of my own to increase the functionality and the ‘ease of use’ of this library.

 SIXTEEN ADDITIONAL, EASY TO USE CUSTOM MACROS

 EW256BMP.DLL adds sixteen (16) new macro commands to the Help writer’s arsenal to inexpensively, and easily, increase the funtionality and appearance of Windows 3.1 Help files. Select the command below for more information.

Registering The DLL With Windows Help

Displaying 256 Color Bitmaps

Extracting Baggage Files From A Help File

Sweeping Up...Deleting Extracted Files On Exit

Changing the text of WinHelp’s Title Bar

Getting your user’s attention with a BEEP

Checking the settings in INI files

Writing values to INI files

Choose from four (4) styles of the Message Box

Getting an answer: The Yes/No Message Box

Removing Close from the system menu

Displaying Your OWN Custom Dialog Box

Printing Multiple Topics In Your Help Files

Caveats (things to beware of) & Known Limitations

Hints & Tips For Using EW256BMP.DLL

How To Register This Shareware DLL

Credits, Acknowledgements, Etc...


RegisterDLL Function
The RegisterDLL Macro

Before you can properly use the 256 Color WinHelp Extension Library properly, you must issue the RegisterDLL macro command. This macro sets up the default directories, the default error message path, and the shareware registration code which disables the “nag” message box that appears in the unregistered shareware version. All of its work is done in the [CONFIG] section of your project’s HPJ file.

 FORMAT & PARAMETERS:

RegisterDLL(qchPath, qError, `UNREGISTERED')

 qchPath is the fully qualified path to the current Help file. qError is the error message path to the same Help file. UNREGISTERED, or any other text enclosed within single quotes, is the text you will place here if using the unregistered shareware version of this DLL. Registered users will need to enter the registration code here to disable the opening “nag” message box that appears when the shareware version of this DLL is first invoked.

 USAGE & SYNTAX:

Use the following syntax in the [CONFIG] section of your HPJ file to execute this macro:

As it appears in the [CONFIG] section of the HPJ file:

 RegisterRoutine(`ew256bmp.dll', `RegisterDLL', `SSS')

 RegisterDLL(qchPath, qError, `UNREGISTERED')

MiniHelp Plus v3.21 users, here is the format in MiniHelp Plus v3.21 source code format:

 .hpjconfig RR(`ew256bmp.dll', `RegisterDLL', `SSS')

 .hpjconfig RegisterDLL(qchPath, qError, `UNREGISTERED')


Displaying 256 Color & 24-Bit Bitmaps

Displaying 256 color and 24-bit bitmaps is actually very easy with the 256 Color WinHelp Extension Library, and was the primary reason the DLL was created. Below is the required process to display a 256 color or 24-bit bitmap in a Windows 3.1 Help file.

First, you must include the 256 color or 24-bit bitmap (16 million colors) in the [BAGGAGE] section of your project’s HPJ file. Using the photograph of the man fishing at left as an example, here is what it might look like:

[BAGGAGE]
fishing.bmp

MiniHelp Plus v3.21 Users:  .hpjbaggage fishing.bmp

Next, you need to issue the RTF embedded window command in your text. User’s of Microsoft Word For Windows or any other RTF-capable word processor will need to format for an embedded window. If you are unsure of what to do, please consult the Microsoft Help Writer’s Authoring Guide, available widely on many BBS’s and online services. Here is the format for the command that placed the 256 color photograph of the man fishing at the top of this topic:

 \_{_ewl ew256bmp.dll, ew256bmp, fishing.bmp_\_}

 Note: LEAVE OUT the underscores above and type everything else as it appears or this will not work!

The ewl sets up the embedded window as left justified with the text that follows wrapped around the right edge of the window. Other possibilities include ewc to place the embedded window as a character in a line of text, or ewr to place the embedded window at the right margin of the Help window, with the text that follows wrapped around the left edge of the embedded window.

The ew256bmp.dll parameter tells Windows Help to look in this DLL to find the window procedure that controls the contents of the embedded window.

The ew256bmp parameter is the window class name of the window procedure that controls the contents of the embedded window.

Lastly, the filename of the bitmap you included as a baggage file in the Help file is entered exactly as you entered it in the [BAGGAGE] section of your project’s HPJ file.

Note that the opening and closing sequences of the backslashes and curly braces are crucial for this to work properly.

 THE PROCESS BEHIND THE SCENES

For those of you who are just a little more than curious, here is what the DLL is doing when Windows 3.1 Help is displaying your bitmapped image in the embedded window. First, the DLL takes the filename specified in the embedded window statement and extracts the bitmapped image file from the baggage file, and writes that file—temporarily— to the same directory and drive the Help file is on.

Second, the file is read into memory, and the image painted to the Help window, complete with a thin border.

Third, and lastly, the temporary file is deleted from the directory and drive to which it was written and the memory it occupies is freed, in order to “clean up house” a bit.

 SEE ALSO:

Caveats (things to beware of) & Known Limitations


The ExtractBag Macro

The ExtractBag macro allows you to extract other files you might want to include as baggage in your Help file. The advantage of this is that you only have one file to distribute (the Help file) and the files cannot be separated at some point along the distribution path. Instead, they will always be a part of the Help file to which they belong.

For example, say you have a couple of waveform sound files you want to make available for use in your Help file. You can distribute the Help file and the two waveform sound files as separate files together in the same “packaging” and hope they remain together. But the risk of all the files not reaching the end user is much, much too great. The better way to do it to insure that the files your Help file needs are always there and available, is to include them as baggage inside the Help file and extract them as you need them.

 FORMAT & PARAMETERS:

ExtractBag(qchPath, `nyuk.wav', `c:\\\\windows\\\\nyuk.wav', qError)

The qchPath parameter is the fully qualified path and filename of the current Help file making the request. The first filename is the name of the baggage file stored in the Help file’s internal file system and must be entered exactly as you entered it in the [BAGGAGE] section of your project’ HPJ file. The second filename is the name of the file you want to copy the file to. Note that you must use four backslashes for separators in the path statement. You should provide a fully qualified path and filename. If no path is specified, the file is written to the specified file in the same directory the Help file is in. The qError parameter is the error message path to the current Help file making the request.

 USAGE & SYNTAX:

Use the following syntax in the [CONFIG] section of your HPJ file to execute this macro:

As it appears in the [CONFIG] section of the HPJ file:

 RegisterRoutine(`ew256bmp.dll', `ExtractBag', `SSSS')

 ExtractBag(qchPath, `nyuk.wav', `c:\\\\windows\\\\nyuk.wav', qError)

MiniHelp Plus v3.21 users, here is the format in MiniHelp Plus v3.21 source code format:

 .hpjconfig RR(`ew256bmp.dll', `ExtractBag', `SSSS')

 .hpjconfig ExtractBag(qchPath, `nyuk.wav', `c:\\\\windows\\\\nyuk.wav', qError)

Of course you may also wish to execute this macro from a hot spot the user selects, or upon entering a topic. For MiniHelp Plus v3.21 users, simply replace the .hpjconfig command with either the .mlink or .tmacro command.

 DISCUSSION:

The possibilities are almost endless as to what you can include as baggage in a Help file. Some suggestions that I can think of off the top of my head are text files containing the full contents of your Help file text or of a particular topic, text files that offer supplemental reading, other Help files, waveform sound files, MIDI music files, AVI video files, programs, etc., etc. See what I mean.

When extracting sound files (and other multimedia files), you should either extract them to the WINDOWS directory or provide the fully qualified path and filename to the macro that uses them, so Windows Help can find the file when it goes to look for it.

 EXAMPLES:

A sound driver of some sort will be necessary to hear these sound files.

Hear Curly of the Three Stooges

Hear a popular sound bite from Terminator 2

 SEE ALSO:

DeleteFile Macro

Caveats (things to beware of) & Known Limitations


The DeleteFile Macro

The DeleteFile macro rids your user’s disk of the files specific to the Help file that you extracted from baggage to a physical file on the disk. You should delete many of the files you extract for your Help file’s use to prevent cluttering up a user’s drive and taking up precious drive space. Kind Windows applications, the catagory your Help file should fall into, clean up after themselves and don't leave a lot of garbage or traces of their existence lying around when they are finished.

This is a truly elective action on your part. Certainly, there will be baggage files that you will want to remain after you or the user has extracted them. Those could be assorted text files, other Help files, or even program files. Other files, such as waveform audio files (or other multimedia files), that are essential for the proper execution of your Help file should be deleted when the Help file closes or when their use is no longer needed. These files tend to be large in size and can take up a lot of unnecessary disk space on your user’s system. Instead, it is much kinder and more beneficial to extract the files from the Help file when you need them and delete them when you are done with them.

 FORMAT & PARAMETERS:

DeleteFile(`c:\\\\windows\\\\nyuk.wav')

The format and parameters for this macro are quite simple. Simply execute the macro and supply the name of the file to delete, complete with the fully qualified path you specified when you extracted the baggage file with the ExtractBag macro.

All the same rules apply to this macro that applied to the ExtractBag macro. Whenever you specify a fully qualified path, you must use four backslashes as the path information separator.

 USAGE & SYNTAX:

Use the following syntax in the [CONFIG] section of your HPJ file to execute this macro:

As it appears in the [CONFIG] section of the HPJ file:

 RegisterRoutine(`ew256bmp.dll', `DeleteFile', `S')

 DeleteFile(`c:\\\\windows\\\\nyuk.wav')

MiniHelp Plus v3.21 users, here is the format in MiniHelp Plus v3.21 source code format:

 .hpjconfig RR(`ew256bmp.dll', `DeleteFile', `S')

 .hpjconfig DeleteFile(`c:\\\\windows\\\\nyuk.wav')

Of course you may also wish to execute this macro from a hot spot the user selects, or upon entering a topic. For MiniHelp Plus v3.21 users, simply replace the .hpjconfig command with either the .mlink or .tmacro command.

When dealing with multimedia files (e.g., WAV, MID, or AVI files), I prefer to execute a macro string that extracts the baggage file, makes use of the file, then deletes the file. This way, I can “clean up” as I go along. This is the way the waveform sound files were handled in the ExtractBag example. Here is the macro string I executed to play them:

 In  MiniHelp Plus v3.21  source file format:

 .mlink ExtractBag(qchPath, `nyuk.wav', `c:\\\\windows\\\\nyuk.wav', qError);sndPlaySound(`nyuk.wav', 0x0011);DeleteFile(`c:\\\\windows\\\\nyuk.wav')^"Hear Curly of the Three Stooges"

 In RTF format:

{_\uldb {_\b Hear Curly of the Three Stooges}}{_\v ! ExtractBag(qchPath, `nyuk.wav', `c:\\\\windows\\\\nyuk.wav', qError);sndPlaySound(`nyuk.wav', 0x0011);DeleteFile(`c:\\\\windows\\\\nyuk.wav')_}

Note that the above examples are typed on one line, even though they appear broken here because of word wrapping. Also, note that you must leave out the underscores in the RTF example.

The above examples extract the baggage (“nyuk.wav”) and write it to a physical file (“c:\windows\nyuk.wav”). Then, the file is played asynchronously (“0x0011”). When the file is finished playing, it is deleted with the DeleteFile macro. This all occurs very rapidly when the user selects the words defined as the hot spot on the screen (“Hear Curly of the Three Stooges”).

 SEE ALSO:

Caveats (things to beware of) & Known Limitations

ExtractBag Macro


Caveats & Known Limitations

There are a few limitations you need to be aware of when using embedded windows in Windows 3.1 Help and when attempting to extract baggage files.

The first is a limitation of Windows 3.1 itself. Windows is not capable of displaying more than one 256 color bitmapped image on the screen at one time if they use different palettes. This limitation does not apply to 16 color bitmaps. If you attempt to display more than one 256 color bitmap on the screen at one time, the first one appears as it should. The second one, however, uses the palette colors of the first and may display incorrectly (see the astronaut photo at right). This is because only one palette may be opened and accessed at a time. If you find the need to display more than one 256 color bitmapped image in the same topic of your Help file, you must either ensure that in no way will more than one be displayed on the screen at a time by placing sufficient intervening text between the two bitmaps or insuring that all the 256 color bitmaps displayed on any one screen at a time share the same color palette. See Creating Bitmaps That Share A Common Palette for a step-by-step guide on how to accomplish this.

This should not be a problem with 24-bit bitmaps, given that 24-bit bitmaps do not contain a “logical palette” and store color information differently.  However, note that I cannot test this premise as I currently have insufficient video memory to utilize 24-bit bitmaps. Not having enough experience with 24-bit bitmaps, I am unable to say for certain about how Windows handles displaying them.

The second thing to be aware of also deals with a quirk in the way Windows handles copying small files. Attempting to extract a baggage file smaller than 550 bytes will result in the file being created on the storage medium but without any contents. If you find the need to extract a baggage file smaller than 550 bytes, I strongly recommend making it part of a larger file, by either adding explanatory text about how to use it…or something.

The third limitation deals with the DeleteFile Macro and was done intentionally by me. You cannot delete any file with the file extension of hlp using this macro. I did this to prevent the Help file itself from being deleted accidentally during debugging sessions. It is very easy to mistakenly pass in the name of the current Help file when specifying the filename to delete. (I almost did it, not once, but twice while debugging this library.) So now, this is an impossibility. Instead, you or the user will have to go in and deliberately delete the Help file either from File Manager or from the DOS prompt.

Fourth, the contents of the embedded window are not printed out when the Help topic is printed. Printing support (responding to the EWM_RENDER message) has not yet been implemented. I do plan to add this in a future version. Most of the architecture exists for implementing it, but I have not yet had a chance to do so, due to time constraints.

And lastly, if while constructing your Help file you attempt to display a 256 color or 24-bit bitmap that isn't in the baggage file system (or if you type its name in wrong), the DLL will stop displaying the 256 color and 24-bit bitmaps. I hope at some point in the future to add an error trapping routine, but in the meantime, make sure you fully test your Help file before distributing it to insure that everything works as it should.

To the best of my knowledge, these are the only limitations I am aware of. In all my testing, I have found this library to be bug-free (as bugs that did crop up were fixed prior to its release). However, should you find a bug that has gone unnoticed on my end, or if you have any questions regarding its use, please contact me by way of one of the four following ways:

 via Snail Mail (U.S. Mail)

Paul Arnote

1208 Randolph

Leavenworth, KS  66048

America Online: address E-Mail to AerosolMan.

Internet: address E-Mail to aerosolman@aol.com

BBS: House Of Cards BBS, (913) 592-4163. Address E-Mail to Paul Arnote


Registration Form

 Name:___________________________________________________________________

 Address:________________________________________________________________

 City/State/ZIP:_________________________________________________________

 Where Did You Obtain Your Copy of EW256BMP.DLL?_________________________

 ________________________________________________________________________

 If from America Online, please state your screen name.

 How would you rate EW256BMP.DLL as meeting your needs? (circle one)

    1   2   3   4   5   6   7   8   9   10

 Suggestions/Comments:___________________________________________________

 ________________________________________________________________________

Thank you for registering your copy of 256 Color WinHelp Library. Please send $20 cash/check/money order to:

 Paul Arnote

 1208 Randolph

 Leavenworth, KS  66048

I will send to you, via U.S. Mail or E-Mail (circle one) the registration code to remove the nag message the library displays with the unregistered shareware version.

 _____ Order  BOTH  EW256BMP.DLL and  MiniHelp Plus v3.21

Send $50 cash/check/money order.

MiniHelp Plus v3.21 will be sent to you on a 3½" DSHD disk,

unless otherwise noted.

 _____ Order  MiniHelp Plus v3.21 ONLY

Send $30 cash/check/money order.

MiniHelp Plus v3.21 will be sent to you on a 3½" DSHD disk,

unless otherwise noted.

Please allow 2 to 4 weeks for delivery of disk-based purchases. (EW256BMP.DLL V2.0)


Credits, Acknowledgements, Etc...
Credits, Acknowledgements, Etc. …

Portions of this DLL were derived from the freeware DLL, EWDLL, by Ron Pacheco, professor of Mathematics and Computer Science at Harding University in Searcy, Arkansas.

The baggage file extraction routine was derived from the programming example provided by Jim Mischel in his book, The Developer’s Guide To WinHelp.Exe. This fine book should be available at a decent bookstore near you and is chocked-full of extremely useful information of all sorts on Help files, from writing them to programming DLLs for Windows 3.1 Help. If they do not have it, ask them to order it. The price is $39.95 without the companion disk, and $49.95 with. It is published by John Wiley & Sons, Inc.

Hopefully, some of the functionality provided here will not be required when Windows ’95 emerges. Microsoft's press releases to date claim that WinHelp v4.0 supports 256 color bitmaps, as well as all sorts of other multimedia files. I don't know about you, but I can hardly wait to see it!

Many thanks to my wife, Barbie, for patiently putting up with me spending many hours in front of the computer getting this library just right.

This Help file was created with MiniHelp Plus v3.21,  the COMPLETE Help Writer’s Authoring Utility.


How To Order MiniHelp Plus v3.21

 MiniHelp Plus v3.21 is a shareware Help Authoring program that creates a Help file from specially formatted ASCII text. The commands are easy to learn and use and it presents a very simple way to create Windows Help files. In fact, creating Windows Help files with MiniHelp Plus v3.21 is easier than using a word processor and very fast (according to some, MiniHelp Plus is a faster way to create Windows Help files than using RTF-capable word processors like Microsoft Word for Windows!).

To order your copy, send $30 cash/check/money order to:

Paul Arnote

1208 Randolph

Leavenworth, KS  66048

Include, on a piece of paper, your name, address, city/state/zip, program name  (MiniHelp Plus v3.21),  disk size, and  E-Mail address. Or, you may send in the registration form included with this Help file. Mark the special area at the bottom of the registration form, specifying if you are ordering only MiniHelp Plus v3.21 or both MiniHelp Plus v3.21 AND EW256BMP.DLL.

Please allow 2-4 weeks for delivery.


Creating Bitmaps That Share

 A Common Palette

Using the same two photographs as used in the Caveats topic of this Help file, you will now notice that the two bitmaps (the earth and the parrot) appear as they should, because they now share the same color palettes. Actually, this bit of “bitmapped-magic” is quite easy to achieve using Windows® Paintbrush. All that is necessary is for you to paste both images into the same Paintbrush picture and copy them back out again to seperate files. Here are the step-by-step instructions for doing so.

 Step One: Open and maximize Windows® Paintbrush. From the Options menu, select Image Attibutes. Select Pels as the unit of measure (a pel is a pixel on the screen) and specify an image size large enough to hold both images (if in doubt, specify 1260 wide by 1024 high). You may find it to your advantage to preselect the rectangular pick tool and hide the color palette bar and the tool bar, thus increasing the work area on your screen.

 Step Two: From the Edit menu, select Paste From... and select the filename of one of the bitmaps that will appear on the screen together. Select the OK button and the selected bitmap will be pasted into the client area of Paintbrush.

 Step Three: Scroll the first bitmap out of view and repeat Step Two for the second and each subsequent bitmap you want to share a palette with.

 Step Four: Using the Pick Tool, select the first bitmap. From the Edit menu, select Copy To... and specify the filename you want to save the new bitmap to. The new bitmap will contain color palette information that is common to both bitmaps. (Note: it is probably best to save it to a slightly different filename than that of the original bitmap, just in case you need to repeat this procedure at some point again in the future.)

 Step Five: Repeat Step Four for the second and each subsequent bitmap you pasted into the client area of Paintbrush. Each bitmap you save will have the same palette information as the first.

Now, all your 256 color bitmaps you wish to display on one screen share a common color palette and will now display properly. Note that, however, there is a limitation to this method. By optimizing the color palette for two different bitmaps that each contain a wide variety of colors, some colors may not display exactly as you might hope due to the number of unique colors exceeding 256. In such a case, the palette is optimized to include a close representation of certain colors that are close in color values.

The best advice I can provide in this instance is to pay close attention to the ways the colors are presented when you paste the second and subsequent bitmaps into Paintbrush. If the picture does not look as good as it would displaying the file by itself, then you are facing a limitation of the 256 color palette and should perhaps start over with this procedure, reversing the order in which the bitmaps are pasted into Paintbrush. Or, perhaps you should find less “demanding” artwork to include in your file.

Here is a special hint. Using a graphics utility, such as Paint Shop Pro, reduce the number of colors in the artwork to 236. The reason is that Windows reserves 20 of the colors in the 256 color palette for its own use. This way, you are less likely to confront a limitation of the color palette when displaying multiple 256 color bitmaps that share a common palette. In fact, in many of the 256 color bitmaps I have used, reducing the palette for the bitmap to 236 has actually improved the display quality of the bitmap.


SetCaptionText Macro
The SetCaptionText Macro

The SetCaptionText macro allows you to change the text displayed on the title bar of the main or secondary Help window at virtually any point in your Help file. You may want to do this at some point in your Help file as the focus shifts to a significantly different topic matter. Or you might want to change the title bar text with every topic to better keep your user oriented to their position within the Help file. Whatever your reasoning, you now have a custom macro command that is very, very easy to use.

 FORMAT & PARAMETERS:

 SetCaptionText(`old window text', `new window text')

It’s really that easy. `old window text' is the current title bar text of the window. `new window text' is the new text you want to display on the window’s title bar.

 USAGE & SYNTAX:

Use the following syntax in the [CONFIG] section of your HPJ file to execute this macro:

As it appears in the [CONFIG] section of the HPJ file:

 RegisterRoutine(`ew256bmp.dll', `SetCaptionText', `SS')

 SetCaptionText(`256 Color WinHelp Extension Library v2.0', `SetCaptionText Macro')

MiniHelp Plus v3.21 users, here is the format in MiniHelp Plus v3.21 source code format:

 .hpjconfig RR(`ew256bmp.dll', `SetCaptionText', `SS')

 .hpjconfig SetCaptionText(`256 Color WinHelp Extension Library v2.0', `SetCaptionText Macro')

The title bar will now display the new text you specify until you change it again with the SetCaptionText macro. This macro may be executed from the HPJ file (as above), as a topic macro, or as a macro hot spot. MiniHelp Plus v3.21 users use .mlink, .tmacro, and .hpjconfig from the MiniHelp Plus source file.

 EXAMPLE:

 Click on the graphic at the left to toggle the title bar text of this main Help window.

The exact implementation of the above hot spot graphic is as follows, using a WinHelp conditional macro to test what state the title bar is in (i.e., what text it is displaying):

In MiniHelp Plus v3.21 source file format:

 .mlink IfThenElse(IsMark(`title'), `DeleteMark(`title');SetCaptionText(`SetCaptionText Macro', `256 Color WinHelp Extension Library: v2.0')', `SaveMark(`title');SetCaptionText(`256 Color WinHelp Extension Library: v2.0', `SetCaptionText Macro')')^"register.bmp"

Note that this will work with the main Help window as well as secondary Help windows.


Paint Shop Pro
Paint Shop Pro, v2.01

 JASC, Inc.

 10901 Red Circle Drive, Suite 340

 Minnetonka, MN  55343  U.S.A.

 Price: 	$69 plus $5 S&H in the U.S.

$69 plus $16 S&H outside the U.S.

All funds must be drawn on a U.S. Bank.


Beep() Macro
The Beep() Macro

The Beep() macro is a simple way to beep a PC’s built in speaker from within a Help file. Possible uses may be to beep every time the user changes topics, to play a series of beeps as part of a macro string execution, or to simply assist in getting the user’s attention.

If a user has a sound card, then the beep will be heard over the user’s computer speakers instead of the PC’s internal speaker. But the nice thing about this macro is that the sound will be heard regardless of whether or not the user has a sound card or sound driver installed. For those users still without a sound card or sound driver, Windows will create a default “beep” over the user’s PC speaker.

Using this custom macro is almost as easy as using the built in WinHelp macros Exit() and Contents().

 FORMAT & PARAMETERS:

 Beep()

The macro takes no parameters.

 USAGE & SYNTAX:

Use the following syntax in the [CONFIG] section of your HPJ file to execute this macro:

As it appears in the [CONFIG] section of the HPJ file:

 RegisterRoutine(`ew256bmp.dll', `Beep', `')

 Beep()

MiniHelp Plus v3.21 users, here is the format in MiniHelp Plus v3.21 source code format:

 .hpjconfig RR(`ew256bmp.dll', `Beep', `')

 .hpjconfig Beep()

This custom macro may be used either as a macro hot spot, a topic macro, or from the [CONFIG] section of the HPJ file. MiniHelp Plus v3.21 users use .mlink, .tmacro, and .hpjconfig from the MiniHelp Plus source file.

 EXAMPLE:

 Click on the button with the musical notes to hear the Beep() macro in action.


The ReadIni Macro

The ReadIni macro allows you to examine the string contents of an INI file entry to see if it matches whatever value to specify. This custom macro returns TRUE if the value you specify exists in the INI file entry, or FALSE if it does not. Thus, you can use this custom macro as an arguement to the conditional WinHelp macros IfThen and IfThenElse.

One possible use for this custom macro might be to check if a certain condition exists on a user’s system before executing a macro, such as using the Help file to write a specific value into an INI file entry if it does not exist. Another possible use might exist to inform the user whether or not a certain condition exists on his/her system (as my implementation does below).

 FORMAT & PARAMETERS:

 ReadIni(`section-name', `entry', `entry-value', `INI filename')

The section-name parameter is the name of the INI file section in which the entry you want to check resides. The entry parameter is the particular entry in the INI file whose value you want to check. The entry-value parameter is the actual entry-value you are checking the presence of. The INI filename parameter is the name of the INI file that contains the entry you want to check.

Note that the last parameter can be a fully-qualified path and filename specifying the INI file. Just remember that when passing a path and filename as a parameter to a WinHelp macro (custom or not), you must use four (4) backslashes where ever you would simply use one (i.e., \\\\).

 USAGE & SYNTAX:

Use the following syntax in the [CONFIG] section of your HPJ file to execute this macro:

As it appears in the [CONFIG] section of the HPJ file:

 RegisterRoutine(`ew256bmp.dll', `ReadIni', `i=SSSS')

 ReadIni(`section-name', `entry', `entry-value', `INI filename')

MiniHelp Plus v3.21 users, here is the format in MiniHelp Plus v3.21 source code format:

 .hpjconfig RR(`ew256bmp.dll', `ReadIni', `i=SSSS')

 .hpjconfig ReadIni(`section-name', `entry', `entry-value', `INI filename')

This macro, like the built-in WinHelp macro IsMark(`text-marker'), is only useful to test a condition using one of WinHelp’s conditinal macros IfThen or IfThenElse.

 EXAMPLE:

 Click on the book button at left to see if screen savers are set up as standalone executables. (Did you know that they can be? Add scr to the ‘programs’ entry of WIN.INI in the [windows] section. Now your screen savers can be ran from the command line with the (space)/s switch or from an icon by specifying this little known command line switch to the icon’s program properties dialog box as the command line. For example, the command line ssmyst.scr /s will start the Mystify screen saver immediately.)

The example above is the following implementation and works very well on my system:

In MiniHelp Plus v3.21 source file format:

 .mlink IfThenElse(ReadIni(`windows',`programs',`com exe bat pif scr',`win.ini'),` InfoMessage  (hwndContext,`Screen savers ARE set up as standalone programs.',`Sample')',` InfoMessage  (hwndContext,`Screen savers ARE NOT set up as standalone programs.', `Sample')')^"bookbtn.bmp"

 DISCUSSION:

Let me discuss with you exactly what is going on here. Using the ReadIni macro, we pass the section-name, entry, entry-value, and INI filename to the macro to see if what we specify in the entry-value parameter exists on the user’s system. If it does, then TRUE (non-zero) is returned, the condition is met, and the first message box is displayed. If it does not exist, then FALSE (zero) is returned, the condition is not met and the second message is displayed.

While this is not a really useful example of using this macro, it is practical (and one I could locate quickly in win.ini to demonstrate). I could just have easily ran a program based on the return value. For example, if the user’s system was already set up to run screen savers as standalone programs, I could have simply started a screen saver by using the ExecProgram macro in place of the first InfoMessage macro. If screen savers haven't been setup as standalone programs in win.ini, then I could have used the customWriteIni macro in this library to set it up for them, then either pop up a message that tells them it has been set up or run a screen saver to prove it has been set up.

Another possible use for this custom macro is to check an INI file to see if your user is a registered user of your software. If they are not, then you could pop up a nagging “Please Register Me” message.


The WriteIni Macro

The WriteIni macro allows you to easily write to or change values in INI files on the user’s system. Say, for example, you were writing a Help file instructing less knowledgable users on how to tweak, tune, and otherwise improve Windows performance. Some of those performance settings are going to involve making changes to various INI files on the user’s system. Either you can leave it to chance...and the user...and hope that the user is capable of making those changes themselves without otherwise wrecking his/her system by doing it wrongly. Or, you can define a hot spot on the screen that the user selects that will perform the action for them...right from your Help file, insuring that the changes are made accurately and without the user ever once having to look at an INI file.

 FORMAT & PARAMETERS:

 WriteIni(`section-name', `entry', `entry-value', `INI-filename')

where `section-name' is the name of the section of the INI file that contains the entry you want to modify/enter, `entry' is the entry you want to modify/enter, `entry-value' is the value assigned to the entry,and `INI-filename' is the INI file you want to modify.

 USAGE & SYNTAX:

Use the following syntax in the [CONFIG] section of your HPJ file to execute this macro:

As it appears in the [CONFIG] section of the HPJ file:

 RegisterRoutine(`ew256bmp.dll', `WriteIni', `SSSS')

 WriteIni(`section-name', `entry', `entry-value', `INI-filename')

MiniHelp Plus v3.21 users, here is the format in MiniHelp Plus v3.21 source code format:

 .hpjconfig RegisterRoutine(`ew256bmp.dll', `WriteIni', `SSSS')

 .hpjconfig WriteIni(`section-name', `entry', `entry-value', `INI-filename')

This macro is perhaps most useful as a hot spot macro. In this way, you allow the user to select whether or not to modify the settings in his/her INI files by selecting various hot spots on the screen. I get extremely upset at anyone who attempts to modify my INI file settings without either letting me know first or giving me the option to not do so. However, you can create your own private INI file with this macro and its values can be checked and compared with the ReadIni macro in this library.

 EXAMPLE:

Click on the hot spot graphic (hypergraphic created with the Hot Spot Editor) at left to test this macro. Click on the “hand and pencil” button graphic to write a test entry to an INI file called TESTINI.INI. Click on the “telescope” button graphic button to view the TESTINI.INI file. Note that the latter will not work until after you have selected the “hand and pencil” graphic.

Here is the exact macro execution that writes the file, TESTINI.INI, which is placed in your Windows directory.

WriteIni(`Test', `Test1', `This is a test of writing data to a private INI file.', `testini.ini')

With this macro, you can write to any INI file, even WIN.INI or SYSTEM.INI. Please, exercise great care when writing to either one of these files, or if writing to PROGMAN.INI, CONTROL.INI, or WINFILE.INI. If word gets around that you are screwing up folk’s INI files (and it won’t take long to get around if you are), soon no one will be using the Help file you put so much of your efforts and energy into creating. No one will want to utilize a file that wreaks havoc on their system, regardless of the quality of the rest of the data being presented.


The Message Box Macros

There are actually four (4) seperate custom macros that allow you to display simple message boxes from Windows Help. Each one is exactly the same, except for the icon displayed in the message box.

 StopMessage displays a message box with the stop icon...

 InfoMessage displays a message box with the information icon...

 ExclaMessage displays a message box with the exclamation point icon...

 SimpleMessage displays a message box with no icon.

Each one of these four macros take exactly the same parameters. Below, I will use the ExclaMessage macro to demonstrate their usage, but just remember that they are all implemented the same. All you have to do is specify which message box you want to display by the macro name.

 FORMAT & PARAMETERS:

 ExclaMessage(hwndContext, `text of message', `message box title bar text')

 StopMessage(hwndContext, `text of message', `message box title bar text')

 InfoMessage(hwndContext, `text of message', `message box title bar text')

 SimpleMessage(hwndContext, `text of message', `message box title bar text')

See what I mean about how each is implemented the same as the others. The parameters for each one are exactly the same. Only the name of the macro changes. hwndContext is the handle to the currently displayed Help topic. If you are executing this from the [CONFIG] section of the HPJ file, use hwndApp instead. `text of message' is the text of the message you want to display in the body of the message box. `message box title bar text' is the text you want to display on the title bar of the message box.

 USAGE & SYNTAX:

Use the following syntax in the [CONFIG] section of your HPJ file to execute this macro:

As it appears in the [CONFIG] section of the HPJ file:

 RegisterRoutine(`ew256bmp.dll', `ExclaMessage', `USS')

 ExclaMessage(hwndApp, `text of message', `message box title bar text')

MiniHelp Plus v3.21 users, here is the format in MiniHelp Plus v3.21 source code format:

 .hpjconfig RR(`ew256bmp.dll', `ExclaMessage', `USS')

 .hpjconfig ExclaMessage(hwndApp, `text of message', `message box title bar text')

Remember, use hwndApp when executing this macro from the [CONFIG] section of the HPJ file and hwndContext when executing this macro as a topic macro or as a hot spot macro. The above shows how it would appear in the [CONFIG] section of the HPJ file.

 EXAMPLE:

Click on the one of the buttons above to see a message box with that corresponding icon. The blank button is for the SimpleMessage macro, which does not display an icon at all.

 DISCUSSION:

From time to time, you might want to display a “longer” message in one of the message boxes. When you do so, you will want to be able to control the appearance of the text by defining where the line of text breaks and forms a new line. Otherwise, the message text will break where ever Windows tells it to break and that might not be to your satisfaction.

Programmers who have used message boxes (and who hasn't) are use to issuing a line break with the \n or \n\r key sequences from within their programs. Unfortunately, this does not work with these message box macros. Instead, you must send the ASCII keycode for a line break, which is \'0A and where 0 is a zero. And, unfortunately, this does not work when the macro is executed from the [CONFIG] section of the HPJ file. To date, I have found no way to force a line break in the message text when executed in this manner. If anyone can figure out how to do this, please let me know. But the line break code works beautifully when the macro is executed either as a topic macro or a hot spot macro. Here is an example:

 StopMessage(hwndContext, `You should wash your hands\'0Abefore using your keyboard.\'0A\'0AIf you don’t wash your hands,\'0Ayour keyboard will get dirty.', `Line Break Example')

Click here to see the above listed example for breaking a line of text in the message box.


The Yes/No Message Box Macro
The YesNoBox Macro

The YesNoBox displays a message box with a choice: Yes or No as an answer to a question. This macro is used in conjunction with one of WinHelp’s conditional macros, IfThen or IfThenElse. If the user selects Yes then the return value is TRUE (non-zero) and the indicated action is carried out. However, if the user selects No then the return value is FALSE (zero) and the indicated action is not carried out (if using the WinHelp conditional macro IfThen) or the alternate action is carried out (if using the WinHelp conditional macro IfThenElse).

The parameters to this macro are almost exactly the same as those for the Message Box macros except that this one returns a value so you can check which button the user selected. Also, this messge box displays the question mark icon......and this behavior cannot be changed.

 FORMAT & PARAMETERS:

 YesNoBox(hwndContext, `text of message', `message box title bar text')

 hwndContext is the handle to the currently displayed Help topic. If executing this from the [CONFIG] section of the HPJ file, use hwndApp instead. `text of message' is the text of the message you want to appear in the message box. 'message box title bar text' is the text you want to display on the title bar of the message box.

 USAGE & SYNTAX:

Use the following syntax in the [CONFIG] section of your HPJ file to execute this macro:

As it appears in the [CONFIG] section of the HPJ file:

 RegisterRoutine(`ew256bmp.dll', `YesNoBox', `i=USS')

 IfThen(YesNoBox(hwndApp, `text of message', `message box title bar text'), `About()')

MiniHelp Plus v3.21 users, here is the format in MiniHelp Plus v3.21 source code format:

 .hpjconfig RR(`ew256bmp.dll', `YesNoBox', `i=USS')

 .hpjconfig IfThen(YesNoBox(hwndApp, `text of message', `message box title bar text'), `About()')

Remember, use hwndApp when executing this macro from the [CONFIG] section of the HPJ file and hwndContext when executing this macro as a topic macro or as a hot spot macro. The above shows how it would appear in the [CONFIG] section of the HPJ file. This example would execute the WinHelp About() macro if the user selected Yes and do nothing if the user selected No.

 EXAMPLE:

 Click on the question mark button at left to see one demonstration of the YesNoBox custom macro.

 Click on the question mark button at left to see another demonstration of the YesNoBox custom macro.

Here are the examples as implemented above (in MiniHelp Plus v3.21 source file format):

 .mlink IfThenElse(YesNoBox(hwndContext, `Are you ready?', `YesNoBox Example'), `ExclaMessage(hwndContext, `You said you are ready.', `YesNoBox Example')', `StopMessage(hwndContext, `You said you are NOT ready.', `YesNoBox Example')')^"quesbtn.bmp"

 .mlink IfThen(YesNoBox(hwndContext, `Are you sure you want to see the About box?', `YesNoBox Example'), `About()')^"quesbtn.bmp"

Note that in the second example, I could have just as easily used the Exit() macro, instead of the About() macro, like this:

 IfThen(YesNoBox(hwndContext, `Are you sure you want to quit?', `256 Color WinHelp Extension Library'), `Exit()')

to prompt the user if he/she is sure they want to quit. Selecting Yes would execute the Exit() macro, while selecting No would do nothing.

Also note that the same rules for creating a line break in the message text apply to this macro as apply to the Message Box macros.


The NoClose Macro

The NoClose macro removes the Close menu item from a Help window’s system menu.

From time to time, you may want to prevent the user from closing secondary Help windows via the system menu. Instead, you might want to take control of the exit procedure so certain things that need to be cleaned up are taken care of before the window is closed.

For example, say you were displaying, playing, and controlling the playback of an AVI clip via hot spots linked to the Video For Windows multimedia library (MMSYSTEM.DLL) extensions in a secondary window. Closing a secondary window that the video clip is playing in via the secondary window’s system menu might leave no way to close the video file and remove its image from the user’s screen.

Therefore, it becomes advantageous to make it impossible to exit the secondary window via the secondary window’s system menu. Instead, it is much better if the user exits the window via a hot spot you have defined in order to close the video clip before closing the secondary window. This way, the video clip’s image is removed from the user’s screen and the AVI file is properly closed.

This custom macro accomplishes this by disabling Close on ANY Help window’s system menu. In fact, if you select the system menu for this Help file, you will notice that the Close menu item on the system menu is grayed out, making it impossible for you to close this Help file via any other means other than the Exit button on the button bar.

 FORMAT & PARAMETERS:

 NoClose(`window title bar text')

 'window title bar text' is the title bar text that appears on the window’s title bar. Usually, this is the text you assigned to the window with either 1) the title = setting in the [OPTIONS] section of the HPJ file, 2) the text you assigned in the window definition statement in the [WINDOWS] section of the HPJ file, or 3) the current text of the window title bar, if you’ve used the SetCaptionText custom macro to assign a new title to the window’s title bar.

 USAGE & SYNTAX:

Use the following syntax in the [CONFIG] section of your HPJ file to execute this macro:

As it appears in the [CONFIG] section of the HPJ file:

 RegisterRoutine(`ew256bmp.dll', `NoClose', `S')

 NoClose(`256 Color WinHelp Extension Library: v2.0')

MiniHelp Plus v3.21 users, here is the format in MiniHelp Plus v3.21 source code format:

 .hpjconfig RR(`ew256bmp.dll', `NoClose', `S')

 .hpjconfig NoClose(`256 Color WinHelp Extension Library: v2.0')

 EXAMPLE:

 Click on the button at left to see an example of a secondary window with Close removed from its system menu and for the syntax of how I created this example.

 DISCUSSION:

Note that in order for this macro to work, the window must have already been created, or is in the process of being created. This custom macro searches all the windows on your desktop to find one whose title bar text matches the text you specify as a parameter. So, use caution, since–in theory at least (and I'm reluctant to test this)–you can use this custom macro to remove Close from the system menu of ANY window open on your desktop.

The reason I'm reluctant to test this is that once I remove Close from the system menu of an application, I might be left with no way to close this window, short of exiting Windows altogether. Any window with this menu item removed from the system menu cannot be closed by double clicking the system menu, and nor will selecting End Task from Task Manager close this window.

Typically, you will want to execute this macro as a topic macro, especially when dealing with a secondary window. If you attempt to execute this macro from the [CONFIG] section of the HPJ file to remove the menu item from the system menu of a secondary window, it will fail since the secondary window (in most instances) does not yet exist. However, you can execute this macro from the [CONFIG] section of the HPJ file to remove Close from the system menu of the main Help window, since the commands in the HPJ file are executed either as the window is being created, or just after its creation.

And, keep in mind that since this disables the Close menu item from the window’s system menu, you MUST make sure to create a hot spot that executes the WinHelp CloseWindow(`window-name') macro. Otherwise, the user will have NO quickly apparent way to clear the window from the screen and the only way to do so is to exit the entire Help file. Also, if you've disabled Close from the system menu of the main Help window, you MUST either create a button on the button bar or a hot spot that executes the Exit() macro so the user has a way to exit your Help file.


Test Window for NoClose
 The NoClose Macro Example

Now, this secondary window was created with Close disabled on the window’s system menu. Here’s how I did it.

Upon displaying this topic, I executed the custom macro NoClose as a topic macro. This way, the window had just been created and since a window existed with the indicated title bar text, it’s system menu could be retrieved and altered.

In MiniHelp Plus v3.21 source file format, that is accomplished as follows:

 .tmacro NoClose(`Test Window')

See, it's actually very easy. But also notice how I made sure to provide a hot spot graphic in the non-scrolling region of the window that allows the user to either print this topic or to close this secondary window. This way, the window can be closed when it’s use is no longer required.


The Custom Dialog Box Macros

 EW256BMP.DLL contains a fully customizable dialog box you can incorporate into virtually any Help file you build. Personally, I got tired of having only WinHelp’s default dialog box to place information regarding my copyright notice and/or other pertinent text into regarding my Help files. Quite simply, there isn’t enough room to do anything worthwhile in the small amount of space provided. And this is why I added in the ability for me–and anyone else who wanted–to define and display a custom dialog box that has much more room to actually serve a worthwhile use.

Using the custom dialog box is rather easy, as well, and involves two (2) custom macros. The first macro, SetDlgText, allows you to set the dialog box title bar text, the textual content of the dialog box, size of the dialog title text, color of the dialog title text, and the color of the dialog box. The second macro, CustomDlg, actually displays the dialog box as you have defined it with the SetDlgText macro.

 FORMAT & PARAMETERS:

 SetDlgText(

`dialog title bar text',

`dialog title text',

`copyright text',

`additional text',

size of dialog title text,

dialog box background color red value,

dialog box background color green value,

dialog box background color blue value,

dialog title text color red value,

dialog title text color green value,

dialog title text color blue value )

You would, of course, type this all in on “one” line (that is, without hitting the ENTER or RETURN key). See Usage & Syntax below for an actual example for implementing this custom macro.

 CustomDlg(`Help window title bar text')

 Help window title bar text is the title bar text of the Help window that owns the dialog box. This can be either the title bar text of the main or a secondary Help window.

 USAGE & SYNTAX:

Use the following syntax in the [CONFIG] section of your HPJ file to execute this macro:

As it appears in the [CONFIG] section of the HPJ file:

 RegisterRoutine(`ew256bmp.dll', `SetDlgText', `SSSSiiiiiii')

 RegisterRoutine(`ew256bmp.dll', `CustomDlg', `S')

 SetDlgText(`About This File...',`256 Color WinHelp Extension Library', `Copyright \'A9 1995, Paul Arnote\'0AAll Rights Reserved.',`EW256BMP.DLL provides you with 16 new, easy to use custom macros for Windows Help.',16,255,255,255,128,0,0)

 CustomDlg(`256 Color WinHelp Extension Library: v2.0')

MiniHelp Plus v3.21 users, here is the format in MiniHelp Plus v3.21 source code format:

 .hpjconfig RR(`ew256bmp.dll', `SetDlgText', `SSSSiiiiiii')

 .hpjconfig RR(`ew256bmp.dll', `CustomDlg', `S')

 .hpjconfig SetDlgText(`About This File...',`256 Color WinHelp Extension Library: v2.0', `Copyright \'A9 1995, Paul Arnote\'0AAll Rights Reserved.',`EW256BMP.DLL provides you with 16 new, easy to use custom macros for Windows Help.',16,255,255,255,128,0,0)

 .hpjconfig CustomDlg(`256 Color WinHelp Extension Library: v2.0')

This is the format for the the About button on the button bar. To create the button, you simply pass the CustomDlg macro as the macro parameter that CreateButton executes when the button is selected. For example:

 CreateButton(`btn_about', `&About', `CustomDlg(`256 Color WinHelp Extension Library: v2.0')')

created the About button on the button bar.

For a discussion about issues you need to be aware of when using the custom dialog box, select the various parameters for SetDlgText which are set up as popup topics.

Also, you may desire to change the text displayed in the dialog box at any time simply by issuing this custom macro again (preferably as a topic macro) and specifying new data to display in the dialog box.


Custom Dialog Title Bar
Dialog Box Title Bar Text

Specify the text you want to appear on the dialog box’s title bar. Enclose the text within single quotes, making sure you use the opening quote (```) at the beginning, and the closing quote (''') at the end, followed by a comma. If you specify an empty string of text (`'), the default title of the dialog box will be About... It is strongly recommended that you execute the SetDlgText macro as a topic macro, preferably from your contents topic.


Custom Dialog Title Text
Dialog Box Title Text

Specify the text you want to appear as the title text for the dialog box. Enclose the text within single quotes, making sure you use the opening quote (```) at the beginning, and the closing quote (''') at the end, followed by a comma. If you specify an empty string of text (`'), no text will be displayed. To force a line break in the text, issue the RTF command for an ASCII line break, \'0A. Note that you cannot control line breaks if you execute this macro from the [CONFIG] section of the HPJ file. It is strongly recommended that you execute the SetDlgText macro as a topic macro, preferably from your contents topic.


Custom Dialog Copyright Text
Dialog Box Copyright Text

Specify the text you want to appear as the custom copyright statement to display in the custom dialog box. Enclose the text within single quotes, making sure you use the opening quote (```) at the beginning, and the closing quote (''') at the end, followed by a comma. If you specify an empty string of text (`'), no text will be displayed. To force a line break in the text, issue the RTF command for an ASCII line break, \'0A. Note that you cannot control line breaks if you execute this macro from the [CONFIG] section of the HPJ file. It is strongly recommended that you execute the SetDlgText macro as a topic macro, preferably from your contents topic.


Custom Dialog Additional Text
Dialog Box Additional Text

Specify the text you want to appear as the custom text to display in the custom dialog box. Enclose the text within single quotes, making sure you use the opening quote (```) at the beginning, and the closing quote (''') at the end, followed by a comma. If you specify an empty string of text (`'), no text will be displayed. To force a line break in the text, issue the RTF command for an ASCII line break, \'0A. Note that you cannot control line breaks if you execute this macro from the [CONFIG] section of the HPJ file. It is strongly recommended that you execute the SetDlgText macro as a topic macro, preferably from your contents topic.


Custom Dialog Title Text Size
Dialog Box Title Text Size

Specify the size you want to display the dialog box’s title text in. The minimum value you can enter here is 10.


Custom Dialog Background Color
Dialog Box Background Color

Specify the background color you want to display the dialog box in using red, green, and blue color values from 0 to 255. Note that you cannot specify a background color darker than a dark gray (64, 64, 64). If you attempt to do so, the dialog box’s color will default to white. This was done to prevent the copyright and additional text fields from fading into the background and becoming invisible. If you need to find out what the color values are for the color you are seeking, go into Windows Paintbrush and double click on one of the colors on the palette. Adjust the slider controls until the color you are seeking is displayed in the color swatch window at the far right. Record the color value numbers and plug them into this macro as the color values to use.


Custom Dialog Title Text Color
Dialog Box Title Text Color

Specify the color you want to display the dialog box title text in using red, green, and blue color values from 0 to 255. Note that you cannot specify a text color that is the same as the dialog box background color. If you attempt to do so, the dialog box’s title text color will default to black. This was done to prevent the title text from fading into the background and becoming invisible. If you need to find out what the color values are for the color you are seeking, go into Windows Paintbrush and double click on one of the colors on the palette. Adjust the slider controls until the color you are seeking is displayed in the color swatch window at the far right. Record the color value numbers and plug them into this macro as the color values to use.


The MPrint Macro

The MPrint macro, short for Multiple-topic Print, allows you to easily print out any number of topics in a Help file. Typically, if you use WinHelp’s Print() macro to try to accomplish this, the first topic prints out just fine but you receive an error message that the next macro(s) cannot be executed while the first one is in progress and the remaining topics do not get printed. The MPrint custom macro gets around that by forcing WinHelp to wait until the current print job is finished before proceding to the next macro. This way, all the topics you specify are printed.

Actually, if you really wanted to, you could use this macro as a type of PrintAll type function to print out all the topics in a Help file. Keeping the 255 character limit in mind regarding the length of macro strings, all one would have to do is save the user’s place in the Help file by saving a text marker (SaveMark), jump to a topic, and use a series of topic macro strings to print out every topic in a Help file. You can return the user to the topic from where he/she originated by issuing the GotoMark macro. See the example at the end of this topic for an example using the very command I used for the Print All button on the button bar.

 FORMAT & PARAMETERS:

 MPrint()

This macro accepts no parameters.

 USAGE & SYNTAX:

Use the following syntax in the [CONFIG] section of your HPJ file to execute this macro:

As it appears in the [CONFIG] section of the HPJ file:

 RegisterRoutine(`ew256bmp.dll', `MPrint', `')

 MPrint():topic jump command:MPrint():topic jump command... and so on

MiniHelp Plus v3.21 users, here is the format in MiniHelp Plus v3.21 source code format:

 .hpjconfig RR(`ew256bmp.dll', `MPrint', `')

 .hpjconfig MPrint():topic jump command:MPrint():topic jump command... and so on

If using this macro either as a topic command or a hot spot macro, replace the colons seperating the macros above with semicolons. However, I HIGHLY recommend using this macro as a topic macro, to enable you to exert more control over the process, as you will soon see in the example below.

 EXAMPLE:

Actually, this example shows you how to use MPrint() to print out all the topics in a Help file using the implementation I've used to create the Print All button above on the button bar. But realize that you don't have to print out all the topics in a Help file; you can print out as many as you want. In fact, you can even print out multiple copies of the same topic, if you so choose. For the sake of brevity, I have chosen to present the following example in MiniHelp Plus v3.21 source file format. Users of Microsoft Word and other Help authoring utilities should consult the documentation for your utility or the Microsoft Help Writer’s Authoring Guide (HAG) for information on creating topic macros.

 First... create an entry in the [CONFIG] section of the HPJ file that creates a button on the button bar that, when executed by the user, jumps to the topic that has all the topic macro definitions for your multiple print job. Note the two additional “friendly” things I have done for the user. I first use the custom macroYesNoBox from this library to inform the user that once this process is started that it cannot be stopped and to give the user a chance to abort the operation at the last moment by selecting NO. The second thing I did was to use the SaveMark macro to save the user’s current position within the Help file so they can be returned to that point once the print sequence is finished.

 .hpjconfig CreateButton(`btn_pall', `Pri&nt All', `IfThen(YesNoBox(hwndApp, `Once Print All has started, it cannot be stopped. Are you sure you want to proceed?', `Print All'), `SaveMark(`mprint'):JI(`',`PRINTALL2')')')

 Second... create a topic that does nothing more than execute a sequential series of topic macros, as follows.

 .topic PRINTALL2

 .tmacro JC(`',2);MPrint();JC(`',3);MPrint();JC(`',4);MPrint();JC(`',5);MPrint()

 .tmacro JC(`',6);MPrint();JC(`',7);MPrint();JC(`',8);MPrint();JC(`',9);MPrint()

 .tmacro JC(`',10);MPrint();JC(`',11);MPrint();JC(`',12);MPrint();JC(`',13);MPrint()

 .tmacro JC(`',14);MPrint();JC(`',15);MPrint();JC(`',16);MPrint();JC(`',17);MPrint()

 .tmacro JC(`',18);MPrint();JC(`',19);MPrint();JC(`',20);MPrint();JC(`',21);MPrint()

 .tmacro JC(`',22);MPrint();JC(`',23);MPrint();JC(`',24);MPrint();JC(`',25);MPrint()

 .tmacro JI(`',`PRINTALL')

 .topic PRINTALL

 .tmacro JC(`',26);MPrint();JC(`',27);MPrint();JC(`',28);MPrint();JC(`',29);MPrint()

 .tmacro JC(`',30);MPrint();JC(`',33);MPrint();JC(`',34);MPrint();JC(`',35);MPrint()

 .tmacro GotoMark(`mprint')

 .tmacro ExclaMessage(hwndApp, `Print job complete.', `Print All')

Note that in the example above, I have chosen to print out the topics in the order in which they appear in the RTF file and the context sensitive Help header file used to create this Help file. However, I could have printed out the topics in any order I specified. When the total length of the sequential macros approaches the 254 character limit, I use the JumpID (JI) macro to go to another topic that then completes the task. I then use the GotoMark macro, which returns the user to his/her previous place within the Help file. Also note that the last macro I execute is the ExclaMessage custom macro in this library to inform the user that the task is complete.

Nothing fancy or extremely difficult about it, but it does take a little planning on your part and the whole process is completely transparent to the end user. Plus, there are advantages to using this method. First, by jumping to the contents topic (JC(`',2)), executing the MPrint() macro, jumping to the next topic, executing the MPrint macro, and so on, I am able to exert absolute control over the process.

Second, there is nothing that says you cannot execute more than one topic macro per topic, and I believe I've demonstrated that here. What we have achieved is to avoid our topic macro strings from exceeding the 254 character limit that the Help Compiler seems to want to throw up on. Note that I have chosen to only jump to and print out four topics per topic macro. This allows us to keep our macro strings below this 254 character limit (I know, the HAG errantly reports that macro strings of 512 characters are accepted. I have not found this to be the case). Once I have jumped to and printed out the four topics, I execute another topic macro that prints out four more, and if needed, repeat this sequence until all the topics I want to allow the user to print out are printed.

Third, this could not have been achieved via execution from the [CONFIG] section of the HPJ file. Due to the large number of topics, our macro string would have gone way past the 254 character limit and the DLL and WinHelp both would have crashed, quite possibly taking all of Windows with it. I know...I tried it.

You will have to take my word for it, because I've spent a lot of time playing with this one. Let the account of my experiences save you the frustration I experienced in trying to get this to work properly. And I really believe that this is, quite possibly, the best and perhaps the only way to efficiently print out all the topics in your Help file using the MPrint custom macro.


EW256BMP.DLL Hints & Tips

This section of the Help file gives you hints and tips about how to effectively use EW256BMP.DLL as well as some do’s and don’ts that weren't covered in the individual explanations of the various custom macros.

One thing to keep in mind is that there is only limited error checking built into this DLL. This makes it extremely important that you follow the directions provided exactly since bad execution of a custom macro could cause the DLL, and even possibly WinHelp and Windows itself, to crash. I haven't built a lot of error checking into the DLL in order to keep the size of the DLL to a minimum. The biggest reason for this is the realization that Help files that contain a LARGE number of 256 color or 24-bit bitmaps, such as this one, quickly grow to enormous size. As such, in order to allow you to distribute this DLL along with the really LARGE Help files it uses on a single diskette, I had to keep the size to a minimum. The DLL, with all of its built in power, is only approximately 23K in total size.

When specifying a 256 color or 24-bit bitmap to display in an embedded window, take extra care to make sure that the file exists and is called by the exact same filename (without the path information) you specified when you added it to the [BAGGAGE] section of the HPJ file. If you specify a filename that does not exist in the baggage file system, the DLL will stop displaying all 256 color or 24-bit bitmaps from that point on. For added insurance, print out the baggage section of your HPJ file so you can refer to the filenames listed there and make sure to completely test your Help file before distribution (something you should be doing, anyway).

 Keep all your bitmaps that you include as baggage in your Help files and plan to display in a seperate directory other than the one that contains the Help file and DLL. Here’s why. When you display a 256 color or 24-bit bitmap in your Help file, that file is extracted from Help’s baggage file system, written to your user’s disk (in this case yours, since you are testing the Help file), read into memory, and deleted. Since EW256BMP.DLL writes the baggage file out to the same directory as the Help file, it overwrites your original. After it is read into memory, EW256BMP.DLL then deletes the file to prevent littering up a user’s hard drive. Thus, your original artwork is... GONE. And that would be such a shame if you didn't have another copy lying around somewhere, especially if it is an original graphic you worked a long time on. Instead, I for example, keep all my bitmaps in a seperate directory (c:\bitmaps) and supply the full path and filename in the baggage section of my HPJ file for each file I'm going to use. If you click on the “Hints” graphic at the beginning of this paragraph, you can see the baggage section of the HPJ file for this Help file to see what I mean.

Using a graphics file conversion utility, such as Paint Shop Pro v2.01 convert your bitmaps to RLE (run length encoded) bitmaps, instead as RGB (red, green, blue) bitmaps. RLE files tend to take up less space than RGB bitmaps, especially when dealing with larger graphics. EW256BMP.DLL can read either file format equally well. Do note, however, that you will not be able to edit an RLE bitmap file with Windows Paintbrush. To do so, you will have to convert the file back into an RGB bitmap, do your editing, and then convert it back into a RLE bitmap. Also, graphic file formats other than these two are not supported.

One tip worth repeating here: when using the NoClose macro to prevent closing a Help window via the window’ system menu, do make sure to provide the user with a way to close the window (i.e., via a hot spot graphic). Otherwise, the user may be left with no way to remove the window from the screen. This is especially true for secondary windows, which have neither a button bar nor a menu other than the system menu.

While I’m busy repeating my self, go back and review the discussion about how to use the MPrint macro. Also, you are not restricted to simply using the JumpContext macro (JC). I just used it because it was simple, short, and sweet. You may use any macro that allows movement between topics and displays them in the main or a secondary Help window. Good candidates include: JumpHash, JumpID (JI), JumpKeyword (JK), GotoMark, Back(), Contents(), JumpContents(`'), Next(), and Prev(). If you employ the last two in the list, only topics assigned a browse sequence will be printed out, and since most Help authors do not assign browse sequence numbers to topics destined to be displayed in popup windows, popups will not be printed. And while we’re on the subject of popups, macros that allow movement between topics but display them in popup windows are not candidates for use as navigating tools with the MPrint macro. Also, remember you can assign browse sequences to any topic in any Help file you write, but it doesn't mean that you have to display the browse buttons. You might want to assign browse sequences simply and soley for the use of printing out the topics in your Help file.

Make sure that EW256BMP.DLL can be found by the Help files that use it. Keep it either in the same directory as the Help file that uses it, or place a copy in the Windows directory. These are the first two places Windows will look for it.

Select the Extract button on the button bar and follow the instructions provided for placing all the custom macro definitions and declarations for EW256BMP.DLL in your HPJ file. Using this method will insure that all the macros are declared properly and will save you considerable time over typing them in yourself.

Sometimes WinHelp will balk at the order of the buttons you add to the button bar. If you find that WinHelp or EW256BMP.DLL is creating a GPF (General Protection Fault) and crashing, try rearranging the order of the buttons you have defined in the [CONFIG] section of the HPJ file. This happened when I was creating this Help file. When I attempted to add the button on the button bar to extract the EW256BMP.INC include file, WinHelp kept crashing. Realizing that everything was fine until I attempted to add that button, I then went back and rearranged the order of the buttons and everything then worked just fine.

This is mostly a DON’T. Don’t use a macro that calls this Help file and displays a given topic in a secondary window. It will not happen. Instead, WinHelp will crash. This means, do not execute a macro similar to the following:

 JI(`ew256bmp.hlp>second', `ANYTOPIC')

which, usually would display the topic named ANYTOPIC of the Help file ew256bmp.hlp in a secondary window called ‘second.’ In fact, it is probably a good idea not to call any other Help file that uses this same DLL while displaying another one that uses EW256BMP.DLL.

Using a graphics utility, such as Paint Shop Pro, reduce the number of colors in the artwork to 236. The reason is that Windows reserves 20 of the colors in the 256 color palette for its own use. This way, you are less likely to confront a limitation of the color palette when displaying multiple 256 color bitmaps that share a common palette. In fact, in many of the 256 color bitmaps I have used, reducing the palette for the bitmap to 236 has actually improved the display quality of the bitmap.


Sample Baggage Section of HPJ file
[BAGGAGE]

c:\bitmaps\rle\champ.bmp

c:\bitmaps\rle\fields.bmp

c:\bitmaps\rle\fishing.bmp

c:\bitmaps\rle\fishlake.bmp

c:\bitmaps\rle\pumpkins.bmp

c:\bitmaps\rle\montana.bmp

c:\bitmaps\rle\astonmon.bmp

c:\bitmaps\rle\astonrgb.bmp

c:\bitmaps\rle\montana2.bmp

c:\bitmaps\rle\oldmill.bmp

c:\bitmaps\rle\btrfly.bmp

c:\bitmaps\rle\einst.bmp

c:\bitmaps\rle\saturn.bmp

c:\bitmaps\rle\bird1.bmp

c:\bitmaps\rle\eagle1.bmp

c:\bitmaps\rle\cat.bmp

c:\bitmaps\rle\flower1.bmp

c:\bitmaps\rle\starcity.bmp

c:\soundwav\errors\nyuk.wav

c:\soundwav\exit\lavista.wav


 The EW256BMP.DLL Include File

You can save yourself considerable time typing and careless errors using EW256BMP.DLL by using the provided “include” file. This file contains all the RegisterRoutine custom macro declarations for the custom macros included in EW256BMP.DLL, as well as the shareware version of the RegisterDLL macro. Simply follow the simple, step by step instructions below.

 First... select the Extract hot spot ‘button’ in the non-scrolling region of this window. The include file (ew256bmp.inc) will be written to your disk in the same directory as this Help file. Select the View hot spot ‘button’ in the non-scrolling region of this window to simply view the include file, displayed in a popup window.

 Second... copy this file to the same directory that contains the HPJ file for the Help file you are writing that uses EW256BMP.DLL. Don't forget to copy the actual DLL to this directory as well.

 Third... place the following line in the [CONFIG] section of your HPJ file:

 #include <ew256bmp.inc>

For MiniHelp Plus v3.21 users, you can do the same thing by executing the following command:

 .hpjconfig #include <ew256bmp.inc>

There...now all the custom macros in EW256BMP.DLL are predefined for your use. All you have to do now is to execute the new, custom macros.

If you want to print out these instructions, select the Print button on the button bar. Select the Back button to return to the topic from which you arrived here from.


Definitions
The EW256BMP.DLL Include File

RR(`ew256bmp.dll',`ExtractBag',`SSSS')

RR(`ew256bmp.dll',`RegisterDLL',`SSS')

RR(`ew256bmp.dll',`DeleteFile',`S')

RR(`ew256bmp.dll', `ExclaMessage', `USS')

RR(`ew256bmp.dll', `SetCaptionText', `SS')

RR(`ew256bmp.dll', `SimpleMessage', `USS')

RR(`ew256bmp.dll', `StopMessage', `USS')

RR(`ew256bmp.dll', `InfoMessage', `USS')

RR(`ew256bmp.dll', `YesNoBox', `i=USS')

RR(`ew256bmp.dll', `ReadIni', `i=SSSS')

RR(`ew256bmp.dll', `WriteIni', `SSSS')

RR(`ew256bmp.dll', `NoClose', `S')

RR(`ew256bmp.dll', `Beep', `')

RR(`ew256bmp.dll', `SetDlgText', `SSSSiiiiiii')

RR(`ew256bmp.dll', `CustomDlg', `S')

RR(`ew256bmp.dll', `MPrint', `')

RegisterDLL(qchPath, qError, `UNREGISTERED')


Created with MiniHelp Plus v3.21
This Help file was created with

 MiniHelp Plus v3.21

 Written by Paul Arnote

 Copyright © 1994.  All Rights Reserved.

 Derived from the original MiniHelp that appeared

 in the January, 1994 issue of Compute Magazine.

 Written by Tom Campbell

 Copyright © 1994.  All Rights Reserved.

If you would like to use MiniHelp Plus v3.21 to create

your Help files, you may obtain your SHAREWARE copy

by either downloading it off of America Online or a

local bulletin board (depending if it has made it there yet).

Or you may write to:

Paul Arnote

1208 Randolph

Leavenworth, Kansas  66048

Send $30.00 to the address above.

Be sure to specify disk size,

density, and program name, as well as your

name & address.  Cash, check or money order.
Please make checks/money orders out to
Paul Arnote.  Registered users

will receive a free Help utility disk, filled with
bitmaps, hot spot graphics, and special
Help DLLs to enhance and add functionality
to your Help file creations.

While this version is not crippled in any way, registration

removes the nag screen that appears when you first start
MiniHelp Plus v3.21.  Please register

your copy if you find it useful and support the shareware concept,

as well as helping to keep me interested enough

to keep improving on this program.

Back To What You Were Doing